home *** CD-ROM | disk | FTP | other *** search
/ Aminet 39 / Aminet 39 (2000)(Schatztruhe)[!][Oct 2000].iso / Aminet / dev / c / ExtrasLib.lha / ExtrasLib / Docs / extras.doc next >
Encoding:
Text File  |  2000-07-17  |  60.5 KB  |  2,355 lines

  1. TABLE OF CONTENTS
  2.  
  3. extras.lib/AddHotKey
  4. extras.lib/AddNNStr
  5. extras.lib/AllocProgressMeterA
  6. extras.lib/ArgYesNo
  7. extras.lib/boopsi_GetGInfo
  8. extras.lib/Busy
  9. extras.lib/CopyString
  10. extras.lib/EnqueueName
  11. extras.lib/EntryToNN
  12. extras.lib/ex_CloseLibs
  13. extras.lib/ex_OpenLibs
  14. extras.lib/EZReq
  15. extras.lib/FindLine
  16. extras.lib/FreeProgressMeter
  17. extras.lib/ftos
  18. extras.lib/GetEntryData
  19. extras.lib/GetGUIScale
  20. extras.lib/GetNNData
  21. extras.lib/GhostRect
  22. extras.lib/IsWhiteSpace
  23. extras.lib/LG_AddGadgets
  24. extras.lib/LG_CreateGadgets
  25. extras.lib/LG_FreeGadgets
  26. extras.lib/LG_GetGadget
  27. extras.lib/LG_GetGadgetAttrs
  28. extras.lib/LG_RemoveGadgets
  29. extras.lib/LG_SetGadgetAttrs
  30. extras.lib/MakeGadgets
  31. extras.lib/MaxStrFontLen
  32. extras.lib/MultiAllocMemA
  33. extras.lib/MultiAllocPooledA
  34. extras.lib/MultiAllocVecA
  35. extras.lib/MultiFreeMemA
  36. extras.lib/MultiFreePooledA
  37. extras.lib/MultiFreeVecA
  38. extras.lib/NextEntry
  39. extras.lib/NextNNStr
  40. extras.lib/NNString_Overview
  41. extras.lib/NNStrLen
  42. extras.lib/NotBusy
  43. extras.lib/OBSOLETECheckInnerWindowSize
  44. extras.lib/OBSOLETECheckWindowSize
  45. extras.lib/OBSOLETEDrawBevelBoxes
  46. extras.lib/PD_PackData
  47. extras.lib/PD_UnpackData
  48. extras.lib/PhraseInStr
  49. extras.lib/RenderText
  50. extras.lib/StrFontLen
  51. extras.lib/Strip
  52. extras.lib/StrIStr
  53. extras.lib/StrLength
  54. extras.lib/thread_EndThread
  55. extras.lib/thread_PutTMsg
  56. extras.lib/thread_PutTMsg_TagList
  57. extras.lib/thread_StartThread
  58. extras.lib/UpdateProgressMeterA
  59. extras.lib/AddHotKey                                     extras.lib/AddHotKey
  60.  
  61.    NAME
  62.        AddHotKey -- Add a hotkey to a Broker.
  63.  
  64.    SYNOPSIS
  65.        cxobj = AddHotKey(Broker,BrokerPort,HotKey,ID)
  66.  
  67.        CxObj *AddHotKey(CxObj *,struct MsgPort *,STRPTR,ULONG)
  68.  
  69.    FUNCTION
  70.        Creates a hotkey for a broker.
  71.  
  72.    INPUTS
  73.        Broker     - Broker CxObj to attach hotkey to. 
  74.        BrokerPort - Broker's MsgPort.
  75.        HotKey     - Null terminated string.
  76.        ID         - Hot keys ID. 
  77.        
  78.    RESULT
  79.        pointer to a CxObj.
  80.  
  81.    EXAMPLE
  82.  
  83.    NOTES
  84.     requires commodities.library to be opened. 
  85.      commodities library already has HotKey()
  86.  
  87.    BUGS
  88.  
  89.    SEE ALSO
  90.  
  91. extras.lib/AddNNStr                                       extras.lib/AddNNStr
  92.  
  93.    NAME
  94.        AddNNStr -- append a normal string to a NNString.
  95.  
  96.    SYNOPSIS
  97.        NewNNStr=AddNNStr(NNStr,New)
  98.  
  99.        STRPTR AddNNStr(STRPTR, STRPTR);
  100.  
  101.    FUNCTION
  102.        
  103.  
  104.    INPUTS
  105.        NNStr - an existing NNString or NULL, if NULL
  106.            the function converts str into an NNString.
  107.        New - a regular NULL terminated string.
  108.  
  109.    RESULT
  110.        A new NNString or NULL, NNStr *WILL* be freed
  111.        regardless of result.  if New is NULL, NNStr will
  112.        be returned.
  113.  
  114.    EXAMPLE
  115.  
  116.    NOTES
  117.  
  118.    BUGS
  119.  
  120.    SEE ALSO
  121.  
  122. extras.lib/AllocProgressMeterA                 extras.lib/AllocProgressMeterA
  123.  
  124.    NAME
  125.        AllocProgressMeterA -- Allocate and initialize a progressmeter.
  126.        AllocProgressMeter -- varargs stub for AllocProgressMeterA().
  127.  
  128.    SYNOPSIS
  129.        meter = AllocProgressMeterA(TagList)
  130.  
  131.        ProgressMeter AllocProgressMeterA( struct TagItem *);
  132.  
  133.        meter = AllocProgressMeterA(Tag, ... )
  134.  
  135.        ProgressMeter AllocProgressMeterA( Tag, ...);
  136.  
  137.    FUNCTION
  138.        This function allocates and initializes a ProgressMeter.
  139.  
  140.    INPUTS
  141.        TagList - 
  142.          One of the following two are required.
  143.          PM_Screen - The screen to place the meter on.
  144.                      (struct Screen *)
  145.          PM_ParentWindow - The parent window of the meter.
  146.                            (struct Window *)
  147.                            
  148.          PM_MsgPort    - Already existing msgport to send the meter's
  149.                          window events through. (Not implemented)
  150.  
  151.          PM_TextAttr   - Font to use in the meter. defaults to the
  152.                          screen font. (struct TextAttr *)
  153.  
  154.          PM_LeftEdge   - Defaults to be centered on PM_ParentWindow
  155.          PM_TopEdge    - or PMScreen.
  156.          PM_MinWidth   - Set the minimum width of the meter's
  157.                          window.
  158.          PM_MinHeight  - Set the minimum height of the meter's
  159.                          window (Not implemented).
  160.  
  161.          PM_WinTitle   - Meter's Window title. (STRPTR) 
  162.  
  163.          PM_LowText    - default "0%"   (STRPTR)  
  164.          PM_HighText   - default "100%" (STRPTR)
  165.  
  166.          PM_MeterFormat - A printf style format string used inside the meter.
  167.                           default "%ld%%". (STRPTR) 
  168.          PM_MeterType   - How PM_MeterFormat is used, 
  169.                             PM_TYPE_PERCENTAGE - uses the percentage of
  170.                               where PM_MeterValue is between PM_LowValue and
  171.                               PM_HighValue for the argument of 
  172.                               PM_MeterFormat.
  173.                             PM_TYPE_NUMBER - Uses the meter's value for the 
  174.                               argument of PM_MeterFormat.
  175.                             PM_TYPE_STRING - Doens't process the meter's 
  176.                               value simply displays the text from 
  177.                               PM_MeterFormat
  178.          PM_MeterLabel    - The label above the meter.  default NULL 
  179.          PM_MinMeterWidth - The minimum meter bar width, the default minimum
  180.                             is 80
  181.  
  182.          PM_MeterPen      - default fillpen 
  183.          PM_MeterBgPen    - default backgroundpen 
  184.          PM_FormatPen     - default highlight text 
  185.          PM_MeterLabelPen - default highlight text 
  186.          PM_LowTextPen    - default text pen 
  187.          PM_HighTextPen   - default text pen 
  188.  
  189.          PM_MeterValue    - (IS) default   0 (LONG) 
  190.          PM_LowValue      - (IS) default   0 (LONG)  
  191.          PM_HighValue     - (IS) default 100 (LONG)
  192.  
  193.          PM_Ticks         -  Ticks to draw under the meter box
  194.                                defaults to 0 for none 
  195.  
  196.          PM_CancelButton - Create a Cancel button? (BOOL)
  197.          PM_CancelText   - Text for cancel button. default "Cancel". (STRPTR)
  198.          PM_QueryCancel  - (S) The number of time the user
  199.                            has pressed the cancel button since the last
  200.                            PM_QueryCancel (ULONG *)  
  201.  
  202.          the following three are not implemented 
  203.          PM_CancelID - Creates an IDCMP_GADGETUP event when the Cancel button
  204.                        is clicked. IntuiMessage->IAddress will be a pointer
  205.                        to a gadget whose GadgetID is taken from this tag.
  206.                        To be used in conjunctoin with the PM_MsgPort tag.
  207.          PM_CancelSigNum  - Sets a signal when the Cancel button is clicked 
  208.          PM_CancelSigTask - Task to signal (struct Task *)    
  209.  
  210.    RESULT
  211.        returns a pointer to a ProgressMeter. or NULL on failure.
  212.  
  213.    EXAMPLE
  214.  
  215.    NOTES
  216.      requires diskfont, exec, gadtools, graphics, intuition & utility
  217.      libraries to be open.
  218.  
  219.    BUGS
  220.        Currently uses SmartRefresh window.
  221.  
  222.    SEE ALSO
  223.        FreeProgressMeter(), UpdateProgressMeterA()
  224.  
  225. extras.lib/ArgYesNo                                       extras.lib/ArgYesNo
  226.  
  227.    NAME
  228.        ArgYesNo - Get a boolean tooltype value.
  229.  
  230.    SYNOPSIS
  231.        yes = ArgYesNo(TTypes,Entry,DefVal)
  232.  
  233.        BOOL ArgYesNo(UBYTE **, STRPTR, DefVal);
  234.  
  235.    FUNCTION
  236.        This function returns the value of a boolean tooltype.
  237.  
  238.    INPUTS
  239.        TTypes - a ToolTypes array returned by ArgArrayInit()
  240.        Entry - the entry to search for.
  241.        DefVal - the default boolean value.
  242.  
  243.    RESULT
  244.        This function only considers the first letter of the
  245.        of the value for the tooltype.  If the first letter
  246.        of the value for the tooltype is 'Y' 'y' 'T' or 't'
  247.        then this function returns 1, if the function finds
  248.        'N' 'n' 'F' or 'f' then it returns 0, if this function
  249.        finds any other character or cannot find the tooltype,
  250.        then the function returns the DefVal.
  251.  
  252.    NOTES
  253.        must link with amiga.lib
  254.  
  255.    SEE ALSO
  256.      amiga.lib/ArgArrayInit(), amiga.lib/ArgString(),
  257.      amiga.lib/ArgInt(), amiga.lib/ArgArrayDone()
  258. extras.lib/boopsi_GetGInfo                         extras.lib/boopsi_GetGInfo
  259.  
  260.    NAME
  261.        boopsi_GetGInfo -- Get the GadgetInfo pointer from common BOOPSI messa
  262. ges
  263.  
  264.    SYNOPSIS
  265.        ginfo = boopsi_GetGInfo(Message)
  266.  
  267.        struct GadgetInfo *boopsi_GetGInfo(Msg);
  268.  
  269.    FUNCTION
  270.        Gets the pointer to the GadgetInfo structure from a BOOPSI
  271.        message.
  272.  
  273.    INPUTS
  274.        Message - BOOPSI message pointer.
  275.  
  276.    RESULT
  277.        pointer to GadgetInfo structure or NULL.
  278.  
  279.    NOTES
  280.        Only handles OM_SET, OM_UPDATE, OM_NOTIFY, GM_HITTEST,
  281.        GM_RENDER, GM_GOACTIVE, GM_HANDLEINPUT, GM_GOINACTIVE
  282.        and GM_LAYOUT methods.
  283.  
  284.    BUGS
  285.  
  286.    SEE ALSO
  287.  
  288. extras.lib/Busy                                               extras.lib/Busy
  289.  
  290.    NAME
  291.        Busy -- displays busy pointer.
  292.  
  293.    SYNOPSIS
  294.        Busy(Window)
  295.  
  296.        void Busy(struct Window *);
  297.  
  298.    FUNCTION
  299.        Blocks input to a window by opening a requester.
  300.  
  301.    INPUTS
  302.        Window - 
  303.  
  304.    RESULT
  305.        None.
  306.  
  307.    NOTES
  308.        requires intuition.library to be open.
  309.  
  310.        This does not change the Window's IDCMP flags, so
  311.        unless you change them your still going to receive
  312.        input events.
  313.        This function does nothing in WB versions less than
  314.        3.0
  315.  
  316.    SEE ALSO
  317.        NotBusy()
  318.  
  319. extras.lib/CopyString                                   extras.lib/CopyString
  320.  
  321.    NAME
  322.        CopyString -- Copy a string
  323.  
  324.    SYNOPSIS
  325.        newstring = CopyString(Source, MemFlags)
  326.  
  327.        STRPTR CopyString(STRPTR, ULONG);
  328.  
  329.    FUNCTION
  330.        Allocates memory using AllocVec and copies a string.
  331.  
  332.    INPUTS
  333.        Source - the source string to copy
  334.        MemFlags - Memory flags see exec.library/AllocVec()
  335.  
  336.    RESULT
  337.        String pointer or NULL. 
  338.  
  339.    NOTES
  340.        newstring must be freed with FreeVec.
  341.  
  342.    SEE ALSO
  343.      exec.library/AllocVec(), exec.library/FreeVec()
  344.  
  345. extras.lib/EnqueueName                                 extras.lib/EnqueueName
  346.  
  347.    NAME
  348.        EnqueueName -- Place a Node in a sorted List.
  349.  
  350.    SYNOPSIS
  351.        EnqueueName(List,Node)
  352.  
  353.        void EnqueueName(struct List *,struct Node*)
  354.  
  355.    FUNCTION
  356.        Place a Node in a sorted List prioritized by Node.ln_Name 
  357.        and ln_Pri.
  358.  
  359.    INPUTS
  360.        List - pointer to a List to place Node into.
  361.        Node - pointer to a Node to be placed in the List.
  362.  
  363.    RESULT
  364.        None.
  365.  
  366.    NOTES
  367.        The List must be presorted by ln_Name and ln_Pri.
  368.        Every node must have its ln_Name field pointing to
  369.        a NULL terminated string.
  370.  
  371. extras.lib/EntryToNN                                     extras.lib/EntryToNN
  372.  
  373.    NAME
  374.        EntryToNN -- Retrieve data from an ENTRY of a database.
  375.  
  376.    SYNOPSIS
  377.        STRPTR EntryToNN(BPTR File, STRPTR EntryName)
  378.  
  379.    FUNCTION
  380.        Get data from a Database, see GetEntryData().
  381.        All the data in the entry is put into an NNString.
  382.        The data can then be parsed with GetNNData()
  383.  
  384. extras.lib/ex_CloseLibs                               extras.lib/ex_CloseLibs
  385.  
  386.    NAME
  387.        ex_CloseLibs -- close multiple libraries.
  388.  
  389.    SYNOPSIS
  390.        ex_CloseLibs(Libs)
  391.  
  392.        void ex_CloseLibs(struct Libs *);
  393.  
  394.    FUNCTION
  395.        Close multiple libraries using the same array of
  396.        struct Libs as used in OpenLibs.
  397.  
  398.    INPUTS
  399.        Libs - A pointer to an array of struct Libs.
  400.  
  401.    RESULT
  402.        none.
  403.  
  404.    NOTES
  405.        exec.library must already be opened.(usually done by the 
  406.        compiler's startup code)
  407.  
  408.        revision 1.1
  409.          corrected autodoc.
  410.          now openes ExecBase on it's own.
  411.        revision 1.2
  412.          renamed to ex_CloseLib due to conflict with reaction.lib
  413.  
  414.    BUGS
  415.  
  416.    SEE ALSO
  417.        ex_OpenLibs()
  418. extras.lib/ex_OpenLibs                                 extras.lib/ex_OpenLibs
  419.  
  420.    NAME
  421.        ex_OpenLibs -- attempt to open multiple libraries.
  422.  
  423.    SYNOPSIS
  424.        success = ex_OpenLibs(Argc,ProgName,ErrorStr,
  425.                    LibVerFmt,ButtonText,Libs)
  426.  
  427.        BOOL ex_OpenLibs(ULONG Argc, STRPTR ProgName, STRPTR ErrorString, 
  428.               STRPTR LibVerFmt, STRPTR ButtonText, struct Libs *Libs);
  429.  
  430.    FUNCTION
  431.        Attempt to open multiple Libraries.  If any library
  432.        fails to open, a requester is opened to notify the 
  433.        user listing all of the libraries that failed to open. 
  434.  
  435.    INPUTS
  436.        Argc       - argc from main()
  437.        ProgName   - pointer to a string containing the 
  438.                    program's name.
  439.        ErrorStr   - error string.  May be NULL.  Defaults to
  440.                    "The following libraries are required:\n";
  441.        LibVerFmt  - printf style format string.  Defaults to 
  442.                     "  %s version %ld\n"
  443.        ButtonText - If a requester is used to display an error
  444.                     message, this text is used in the button.
  445.                     Defaults to "Ok"
  446.        Libs       - an array of libraries to open.
  447.  
  448.    RESULT
  449.        return 0 on failure and non-zero on success.
  450.  
  451.    EXAMPLE
  452.        struct IntuitionBase *IntuitionBase;
  453.        struct GfxBase *GfxBase;
  454.        struct Library *GadToolsBase;
  455.        
  456.        struct Libs MyLibs[]=
  457.        {
  458.          &IntuitionBase,"intuition.library"    ,37, 0,
  459.          &GfxBase      ,"graphics.library"     ,37, 0,
  460.          &GadToolsBase ,"gadtools.library"     ,37, 0,
  461.          &LocaleBase   ,"datatypes.library"    ,39, OLF_OPTIONAL,
  462.          0,0,0
  463.        };
  464.  
  465.        void main(int argc, char **argv) 
  466.        {
  467.          if(ex_OpenLibs(arcg,"MyProgram",0,0,0,MyLibs))
  468.          {
  469.            ...
  470.            CloseLibs(MyLibs);
  471.          }
  472.        }
  473.  
  474.    NOTES
  475.        On error, this function will automatically display an 
  476.        intuition requester if Argc=0 or print error information 
  477.        out to STDIO if Argc>0.
  478.  
  479.        exec.library must already be open.(usually done by the 
  480.        compiler's startup code)
  481.  
  482.        revision 1.1
  483.          autodoc fix
  484.          now opens exec.library on it's own.
  485.        revision 1.2
  486.          renamed to ex_OpenLib due to conflict with reaction.lib
  487.  
  488.        
  489.  
  490.    BUGS
  491.  
  492.    SEE ALSO
  493.        ex_CloseLibs()
  494. extras.lib/EZReq                                             extras.lib/EZReq
  495.  
  496.    NAME
  497.        EZReq -- create an Intuition EasyRequest.
  498.  
  499.    SYNOPSIS
  500.        retval = EZReq(Win, IDCMP_ptr, Title, Text,
  501.                        ButtonText,Arg,...)
  502.  
  503.        LONG EZReq(struct Window *, ULONG *, STRPTR, STRPTR, 
  504.                   STRPTR, ULONG, ...);
  505.  
  506.    FUNCTION
  507.        This function provides an easier method to use the 
  508.        intuition/EasyRequestArgs() function.
  509.  
  510.    INPUTS
  511.        Win -
  512.        IDCMP_ptr - 
  513.        Title -
  514.        Text -
  515.        ButtonText -
  516.        Arg -
  517.  
  518.    RESULT
  519.  
  520.    EXAMPLE
  521.  
  522.    NOTES
  523.        requires the exec.library to be open, automatically opens
  524.        intuition.library.
  525.  
  526.    BUGS
  527.  
  528.    SEE ALSO
  529.  
  530. extras.lib/FindLine                                       extras.lib/FindLine
  531.  
  532.    NAME
  533.        FindLine - find the next matching line in a file.
  534.  
  535.    SYNOPSIS
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.    FUNCTION
  543.  
  544.  
  545.    INPUTS
  546.  
  547.    RESULT
  548.  
  549.    EXAMPLE
  550.  
  551.    NOTES
  552.  
  553.    BUGS
  554.  
  555.    SEE ALSO
  556.  
  557. extras.lib/FreeProgressMeter                     extras.lib/FreeProgressMeter
  558.  
  559.    NAME
  560.        FreeProgressMeter -- Close a PregressMeter.
  561.  
  562.    SYNOPSIS
  563.        FreeProgressMeter(PM)
  564.  
  565.        void FreeProgressMeter(ProgressMeter );
  566.  
  567.    FUNCTION
  568.        Close and deallocated a ProgressMeter.
  569.  
  570.    INPUTS
  571.        PM - pointer to an existing ProgressMeter or NULL.
  572.  
  573.    RESULT
  574.        none.
  575.  
  576.    EXAMPLE
  577.  
  578.    NOTES
  579.      requires diskfont, exec, gadtools, graphics, intuition & utility
  580.      libraries to be open.
  581.  
  582.    BUGS
  583.  
  584.    SEE ALSO
  585.        AllocProgressMeterA(), UpdateProgressMeterA()
  586.  
  587. extras.lib/ftos                                               extras.lib/ftos
  588.  
  589.    NAME
  590.        ftos - Convert a float to a string
  591.  
  592.    SYNOPSIS
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.    FUNCTION
  600.  
  601.  
  602.    INPUTS
  603.  
  604.    RESULT
  605.  
  606.    EXAMPLE
  607.  
  608.    NOTES
  609.  
  610.    BUGS
  611.  
  612.    SEE ALSO
  613.  
  614. extras.lib/GetEntryData                               extras.lib/GetEntryData
  615.  
  616.    NAME
  617.        GetEntryData -- Retrieve data from an ENTRY of a database.
  618.  
  619.    SYNOPSIS
  620.        GetEntryDataA(File, EntryName, Items) -- NOT implemented --
  621.  
  622.        BOOL GetEntryDataA(BPTR, STRPTR struct EItem *);
  623.  
  624.        GetEntryData(File, EntryName, Items, ... )
  625.  
  626.        BOOL GetEntryData(BPTR, STRPTR, STRPTR, ... );
  627.  
  628.    FUNCTION
  629.        Retrieve data from a simple ENTRY based database.
  630.  
  631.    INPUTS
  632.        File - an AmigaDOS BPTR to a file.
  633.        Name - an array of struct Etems, the last struct EItem should have
  634.               it's Name field set to NULL. (see example)
  635.    RESULT
  636.        returns 0 on failure, possibly due to EOF, improper file format, or
  637.        lack of memory.  
  638.     
  639.        To support multiple occurances of an item Name in an Entry, this 
  640.        function returns NNStrings.  The strings are stored end to end in 
  641.        the order that they were read from the file.
  642.  
  643.        On success, each EItem.ReturnString either points to an NNString,
  644.        or NULL if no data for that Name was found.
  645.  
  646.        On failure, all EItem.ReturnStrings are NULL, and any data collected
  647.        is freed.
  648.  
  649.    EXAMPLE
  650.        STRPTR title,desc;
  651.        BPTR File;
  652.  
  653.        if(GetEntryData(File,"ENTRY",
  654.                             "TITLE"  ,&title,
  655.                             "DESC"   ,&desc,
  656.                                0))
  657.        {
  658.          if(title)
  659.          {
  660.            printf("%s - ",title);
  661.            FreeVec(title);
  662.          }
  663.  
  664.          if(desc)
  665.          {
  666.            printf("%s\n");
  667.            FreeVec(desc);
  668.          }
  669.        }
  670.  
  671.  
  672.    NOTES
  673.        The database file format is an ASCII text file, and consists
  674.        of "ENTRY"'s, that look like this:
  675.  
  676.        <ENTRYNAME>
  677.        {
  678.          <ITEMNAME> = <data>
  679.          <ITEMNAME> = <data>
  680.        }
  681.  
  682.        an example file format from above might be:
  683.  
  684.        ENTRY
  685.        {
  686.          TITLE=Cows 'R Us
  687.          DESC=All you want to know about beef.
  688.        }
  689.  
  690.        case of <ENTRYNAME> and <ITEMNAMES> is not important.
  691.        the equal sign is required.
  692.        
  693.    HISTORY
  694.        This code probably isn't all that usefull, but it was the
  695.        code behind the database of now defunct Tampa Bay Amiga Group's
  696.        Amiga Support Directory.  Unfortunately, TBAG died before the
  697.        ASD could begine to grow, and I haven't used this code since.
  698.  
  699.    BUGS
  700.        Not reentrant.
  701.  
  702.    SEE ALSO
  703.        ProcessNNStr, AddNNStr(), NextNNStr(), EntryToNN()
  704.  
  705. extras.lib/GetGUIScale                                 extras.lib/GetGUIScale
  706.  
  707.    NAME
  708.        GetGUIScale -- Find the appropriate scale for an
  709.                       interface.
  710.  
  711.    SYNOPSIS
  712.        success = GetGUIScale(TAttr, Strings, &XScale, &YScale)
  713.  
  714.        BOOL GetGUIScale(struct TextAttr *, struct GUI_String *,
  715.                         float *, float *);
  716.  
  717.    FUNCTION
  718.        This function figures out the minimum size an interface
  719.        should be so that all of the Strings will fit.
  720.  
  721.    INPUTS
  722.        TAttr - The TextAttr to be used for the strings.
  723.        Strings - A NULL terminated array of GUI_String containing
  724.                  the Strings to used in the interface and the maximum
  725.                  size each string can be before the interface needs
  726.                  to be enlarged.
  727.        XScale - the address of a float to contain the X scale factor.
  728.        YScale - the address of a float to contain the Y scale factor. 
  729.  
  730.    RESULT
  731.        This function returns non-zero on success, and will have the X &
  732.        YScale values set apropriately.  Returns NULL on failure if the
  733.        font specified in TAttr can not be opened, and X & YScale will be
  734.        set to -1.
  735.  
  736.    NOTES
  737.        requires diskfont.library to be open.
  738.  
  739.        The reason this function sets X & YScale to -1 on failure is to
  740.        also cause CheckWindowSize() and CheckInnerWindowSize to fail.
  741.        This way you can simply:
  742.        GetGUIScale(ta,strings,&xscale,&yscale)
  743.        if(!CheckWindwoWidth(scr,winwidth,winheight,xscale,yscale))
  744.        { ... revert to topaz.8 ... 
  745.        }
  746.  
  747.        The GUI_String specifies the maximum size a string can be before
  748.        the interface should be scaled horizontally.  For example, if you
  749.        have a BUTTON_KIND gadget that is 100 pixels wide, then you may
  750.        want to set the maximum size for the string in that gadget to 90.  
  751.        (ie.
  752.             struct GUI_String gs[]=
  753.             {
  754.               "Button Text", 90,
  755.               0,0
  756.             };
  757.        )
  758.  
  759.    SEE ALSO
  760.        MakeGadgets()
  761.  
  762. extras.lib/GetNNData                                     extras.lib/GetNNData
  763.  
  764.    NAME
  765.        GetNNData 
  766.  
  767.    SYNOPSIS
  768.        STRPTR GetNNData(STRPTR NNStr, STRPTR Name, STRPTR DefVal);
  769.  
  770.    FUNCTION
  771.        Retrieves data from a NNString.
  772.  
  773.        nnstr="TITLE=Joe\0COLOR=Green\0\0"
  774.  
  775.        t=GetNNData(nnstr,"TITLE","None");
  776.  
  777.        t will equal "Joe"
  778.  
  779.    SEE ALSO
  780.  
  781. extras.lib/GhostRect                                     extras.lib/GhostRect
  782.  
  783.    NAME
  784.        GhostRect -- Cover a rectangular are with 
  785.                     a ghosted pattern.
  786.  
  787.    SYNOPSIS
  788.        GhostRect(RP, Pen, X0, Y0, X1, Y1)
  789.  
  790.        void GhostRect(struct RastPort *, ULONG, 
  791.             WORD, WORD, WORD, WORD); 
  792.  
  793.    FUNCTION
  794.        Covers a rectangular area with a ghosted pattern
  795.        using the specified pen number.
  796.  
  797.    INPUTS
  798.        RP - Pointer to a RastPort.
  799.        Pen - the pen number to use for the pattern.
  800.        X0 - left edge 
  801.        Y0 - top edge
  802.        X1 - right edge
  803.        Y1 - bottom edge
  804.  
  805.    BUGS
  806.        The following MUST be true: X1>=X0  Y1>=Y0
  807.  
  808. extras.lib/IsWhiteSpace                               extras.lib/IsWhiteSpace
  809.  
  810.    NAME
  811.        IsWhiteSpace -- Is a character a "white-space"
  812.  
  813.    SYNOPSIS
  814.        IsWhiteSpace(Char)
  815.  
  816.        BOOL IsWhiteSpace(char);
  817.  
  818.    FUNCTION
  819.        Indicate whether or not a character is a "white-space"
  820.  
  821.    INPUTS
  822.        Char - a letter.
  823.  
  824.    RESULT
  825.        non-0 if Char is " "(space), "\t"(tab), or "\n"(cr)
  826.  
  827.    EXAMPLE
  828.  
  829.    NOTES
  830.  
  831.    BUGS
  832.  
  833.    SEE ALSO
  834.  
  835. extras.lib/LG_AddGadgets                             extras.lib/LG_AddGadgets
  836.  
  837.    NAME
  838.        LG_AddGadgets - Add gadgets to a window.
  839.  
  840.    SYNOPSIS
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.    FUNCTION
  848.  
  849.  
  850.    INPUTS
  851.  
  852.    RESULT
  853.  
  854.    EXAMPLE
  855.  
  856.    NOTES
  857.  
  858.    BUGS
  859.  
  860.    SEE ALSO
  861.  
  862. extras.lib/LG_CreateGadgets                       extras.lib/LG_CreateGadgets
  863.  
  864.    NAME
  865.        LG_CreateGadgets -- Create multiple Gadtools gadgets.
  866.  
  867.    SYNOPSIS
  868.        gcontrol = LG_CreateGadgets(Tags)
  869.  
  870.        struct LG_Control *LG_CreateGadgets(Tag Tags, ...);
  871.  
  872.    FUNCTION
  873.        Creates multiple Gadtools, with some layout options.
  874.  
  875.    INPUTS
  876.        Tags (see <extras/layougtgt.h>)
  877.  
  878.          LG_LeftEdge, LG_XPos - Position of gadget
  879.          LG_TopEdge,  LG_YPos - Position of gadget
  880.              The position of the gadget will depend on these attributes
  881.              and the LG_Justification attribute.  Also see the relational
  882.              macros in <extras/layoutgt.h>
  883.          LG_Width  - Gadget width
  884.          LG_Height - Gadget height
  885.  
  886.            for the following see the NewGadget structure in 
  887.            <libraries/gadtools.h>
  888.          LG_GadgetText
  889.          LG_TextAttr
  890.          LG_GadgetID
  891.          LG_Flags
  892.          LG_VisualInfo
  893.          LG_UserData
  894.          LG_GadgetKind
  895.          LG_GadgetTags
  896.          LG_GadgetTagList
  897.  
  898.          LG_OffsetX - global offset from left of window
  899.          LG_OffsetY - global offset from top of window 
  900.             These two set to topleft of the domain.
  901.             Also these will be added to LG_UseScreenOffsets
  902.             or LG_UseWindowOffsets if set.
  903.  
  904.          LG_LabelFlags - see LGLF_ 
  905.  
  906.          LG_ScaleX - Multiply gadget width and position by these.
  907.                      (percent * 65536)
  908.          LG_ScaleY - Multiply gadget height and position by these.
  909.                      (percent * 65536)
  910.  
  911.          LG_Justification - Sets the "handle" of the gadget.
  912.  
  913.          LG_UseScreenOffsets - Sets global offsets based on Window border 
  914.                            dimensions specified in the Screen structure
  915.          LG_UseWindowOffsets - Sets global offsets based on Window border 
  916.                            dimensions
  917.  
  918.          LG_EraseRemoved - If set gadgets erase themselves when they are 
  919.                            removed using LG_RemoveGadgets
  920.  
  921.          LG_KeyClass  - Not used 
  922.          LG_KeyString - A string of characters that "activate" that 
  923.               gadget, if not specified, LG_CreateGadget() will scan 
  924.               the gadget label for the appropriate string.  This 
  925.               attribute is cleared after each LG_CreateGadget
  926.                attribute
  927.          LG_ErrorCode - Not used
  928.  
  929.          LG_Bounds - set offsets or domain area for gadgets
  930.          LG_BoundsLeft   - Left of domain. (Alias for LG_OffsetX)
  931.          LG_BoundsTop    - Top of domain.  (Alias for LG_OffsetY)
  932.          LG_BoundsWidth  - Width of domain.
  933.          LG_BoundsHeight - Height of domain.
  934.  
  935.          LG_RelHorizGap - Gap between certain relative operations
  936.          LG_RelVertGap  - Gap between certain relative operations
  937.  
  938.          LG_HorizCells - Sets the number of columns in a table.
  939.          LG_VertCells - Sets the number of rows in a table. 
  940.            Sets the number of cells in a table.  The table's pixel size
  941.            is the current LG_Bound size.  These attributes work in 
  942.            conjunction with the LG_REL_CELL_ macros defined in 
  943.            <extras/layoutgt.h>
  944.            
  945.          LG_SkipGadgets - Skip the next ti_Data LG_CreateGadgets and 
  946.            all Tags in between.
  947.  
  948.    RESULT
  949.        returns NULL on failure, or a pointer the LG_Control structure 
  950.        defined in <extras/layoutgt.h>
  951.  
  952.    EXAMPLE
  953.        See the supplied example, if there are any.
  954.  
  955.    NOTES
  956.        Gadgets created by LG_CreateGadgets() Must be freed using 
  957.        LG_FreeGadgets OR Removed from it's Window using 
  958.        LG_RemoveGadgets *BEFORE* the window is closed
  959.  
  960.    BUGS
  961.  
  962.    SEE ALSO
  963.        LG_FreeGadgets, LG_RemoveGadgets, LG_AddGadgets, LG_RemoveGadgets,
  964.  
  965. extras.lib/LG_FreeGadgets                           extras.lib/LG_FreeGadgets
  966.  
  967.    NAME
  968.        LG_FreeGadgets - free gadgets allocated be LG_CreateGadgets.
  969.  
  970.    SYNOPSIS
  971.        LG_FeeeGadgets(Control)
  972.  
  973.        void LG_FreeGadgets(struct LG_Control);
  974.  
  975.    FUNCTION
  976.        deallocates gadgets ans support structures allocated by 
  977.         LG_CreateGadget
  978.  
  979.    INPUTS
  980.        Con - pointer to structure returned by LG_CreateGadgets.
  981.  
  982.    RESULT
  983.  
  984.    EXAMPLE
  985.  
  986.    NOTES
  987.        Gadgets created by LG_CreateGadgets() Must be freed using 
  988.        LG_FreeGadgets OR Removed from it's Window using 
  989.        LG_RemoveGadgets *BEFORE* the window is closed
  990.  
  991.    BUGS
  992.  
  993.    SEE ALSO
  994.  
  995. extras.lib/LG_GetGadget                               extras.lib/LG_GetGadget
  996.  
  997.    NAME
  998.        LG_GetGadget - get a gadget pointer using Gadget ID.
  999.  
  1000.    SYNOPSIS
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.    FUNCTION
  1008.  
  1009.  
  1010.    INPUTS
  1011.  
  1012.    RESULT
  1013.  
  1014.    EXAMPLE
  1015.  
  1016.    NOTES
  1017.  
  1018.    BUGS
  1019.  
  1020.    SEE ALSO
  1021.  
  1022. extras.lib/LG_GetGadgetAttrs                     extras.lib/LG_GetGadgetAttrs
  1023.  
  1024.    NAME
  1025.        LG_GetGadgetAttrs
  1026.  
  1027.    SYNOPSIS
  1028.  
  1029.  
  1030.  
  1031.  
  1032.  
  1033.  
  1034.    FUNCTION
  1035.  
  1036.  
  1037.    INPUTS
  1038.  
  1039.    RESULT
  1040.  
  1041.    EXAMPLE
  1042.  
  1043.    NOTES
  1044.  
  1045.    BUGS
  1046.  
  1047.    SEE ALSO
  1048.  
  1049. extras.lib/LG_RemoveGadgets                       extras.lib/LG_RemoveGadgets
  1050.  
  1051.    NAME
  1052.        LG_RemoveGadgets - remove gadgets from a window.
  1053.  
  1054.    SYNOPSIS
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.    FUNCTION
  1062.  
  1063.  
  1064.    INPUTS
  1065.  
  1066.    RESULT
  1067.  
  1068.    EXAMPLE
  1069.  
  1070.    NOTES
  1071.  
  1072.    BUGS
  1073.  
  1074.    SEE ALSO
  1075.  
  1076. extras.lib/LG_SetGadgetAttrs                     extras.lib/LG_SetGadgetAttrs
  1077.  
  1078.    NAME
  1079.        LG_SetGadgetAttrs - set gadget attrs.
  1080.  
  1081.    SYNOPSIS
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.    FUNCTION
  1089.  
  1090.  
  1091.    INPUTS
  1092.  
  1093.    RESULT
  1094.  
  1095.    EXAMPLE
  1096.  
  1097.    NOTES
  1098.  
  1099.    BUGS
  1100.  
  1101.    SEE ALSO
  1102.  
  1103. extras.lib/MakeGadgets                                 extras.lib/MakeGadgets
  1104.  
  1105.    NAME
  1106.        MakeGadgets -- Layout Gadtools gadgets. *OBSOLETE*
  1107.  
  1108.    SYNOPSIS
  1109.        Gadget = MakeGedgets(Scr, VisualInfo, NumGadgets, NewGads, 
  1110.                NewGadTags, NewGadKinds, Gadgets, TextAttr, XScale,
  1111.                YScale)
  1112.  
  1113.        struct Gadget * MakeGadgets(struct Screen *,APTR ,ULONG,
  1114.                struct NewGadgets *, ULONG *, ULONG *,
  1115.                struct Gadget **, struct TextAttr *, float, float);
  1116.  
  1117.    FUNCTION
  1118.        This function will create Gadgets from an array of
  1119.        Gadtools NewGadgets, scaling the gadgets to the size
  1120.        specified.
  1121.  
  1122.    INPUTS
  1123.        Scr - This is the screen that the window containing these
  1124.                 gadgets are destine for.  This is only used to get
  1125.                 the WBorX values used to offset the gadgets from
  1126.                 the window border.  *Set this to NULL if the gadgets
  1127.                 are destine for a GimmeZeroZero window*.
  1128.        VisualInfo - VisualInfo pointer from gadtools/GetVisualInfo().
  1129.        NumGadgets - the number of gadgets to process.
  1130.        NewGads - array of struct NewGadget.
  1131.        NewGadTags - array of ULONGS to be processed as TagItems.
  1132.              All the gadget's tags are in this single array.
  1133.              (In the same fashion as GadToolsBox) 
  1134.              Individual tag arrays are NULL(TAG_DONE) terminated,
  1135.              And you may use TAG_MORE for additional Tags per gadget,
  1136.              but the array still must be NULL terminated.
  1137.        NewGadKinds - array of ULONGs, (BUTTON_KIND etc.)
  1138.        Gadgets - (struct Gadget **) Pointer to an array of
  1139.              Gadget pointers.  The Gadgets created by this
  1140.              function can be referenced by the ng_GadgetID of
  1141.              the source NewGadget.
  1142.        TextAttr - (struct TextAttr *) This TextAttr to used for
  1143.              gadgets whose ng_TextAttr is NULL.
  1144.        XScale - the x factor to scale the gadgets.
  1145.        YScale - the y factor to scale the gadgets.
  1146.              
  1147.    RESULT
  1148.        returns a pointer to the context from CreateContext()
  1149.        or NULL on failure.
  1150.  
  1151.    EXAMPLE
  1152.  
  1153.    NOTES
  1154.        requires diskfont, gadtools & utility libraries to
  1155.        be open.
  1156.  
  1157.        This function has a special flag for NewGadget->ng_Flags,
  1158.        NG_FITLABEL.  This flag tells the function to adjust the
  1159.        ng_LeftEdge and/or Width if the PLACETEXT_LEFT or RIGHT
  1160.        flags are set, and the ng_TopEdge and/or Height if the
  1161.        PLACETEXT_ABOVE or BELOW flags are set, so that the 
  1162.        ng_GadgetText will fit inside the area specified for the
  1163.        gadget.  You must also specify one of the PLACETEXT_?
  1164.        values or this will not work.
  1165.  
  1166.        For GimmeZeroZero windows set Scr to NULL.
  1167.        
  1168.        This function will not modify any of the arrays 
  1169.        (ie. NewGads, NewGadTags), this way if you have
  1170.        an interface that opens & closes multiple times
  1171.        (like commodities) you will not have to reinitialize
  1172.        the arrays.
  1173.  
  1174.        Every ng_GadgetID should be unique and none may have a
  1175.        larger value than the number of elements in the array
  1176.        pointed to by Gadgets.
  1177.  
  1178.        GTLV_ShowSelected works differently with this function.
  1179.        specify -1l for the display only gadget, specify the 
  1180.        gadget _id_ of the string gadget for the editable gadget
  1181.        (the string gadget must be created before the listview).
  1182.        Gadtools wants a NULL or poiner to a gadget for this value
  1183.        but this is taken care by this function. 
  1184.  
  1185.        Gadgets created by this function can be freed with a 
  1186.        call to FreeGadgets().
  1187.  
  1188.    BUGS
  1189.  
  1190.    SEE ALSO
  1191.        GetGUIScale()
  1192. extras.lib/MaxStrFontLen                             extras.lib/MaxStrFontLen
  1193.  
  1194.    NAME
  1195.        MaxStrFontLen - get the maximum pixel length of a
  1196.        string containg N cahracters. 
  1197.  
  1198.    SYNOPSIS
  1199.        length=MaxStrFontLen(Font, Chars, LowChar, HighChar)
  1200.  
  1201.        LONG MaxStrFontLen(struct TextFont *, ULONG, UBYTE, UBYTE);
  1202.  
  1203.    FUNCTION
  1204.        This function returns the maximum number of pixels
  1205.        a string with a certain number of characters could
  1206.        occupy.
  1207.  
  1208.    INPUTS
  1209.        Font - struct TextFont * previously opened by 
  1210.               OpenFont() or OpenDiskFont().
  1211.        Chars - the max number characters in a string.
  1212.        LowChar - the ASCII number of lowest character
  1213.                  that could be in a string.
  1214.        HighChar - the ASCII number of the highest character
  1215.                   that could be in a string.
  1216.  
  1217.    EXAMPLE
  1218.         find the longest pixel length of a number 
  1219.         upto 3 digits 
  1220.        long maxnumberlen;
  1221.        struct TextFont *tf;
  1222.  
  1223.        maxnumberlen=MaxStrFontLen(tf,3,'0','9');
  1224.  
  1225.    RESULT
  1226.        the pixel length or 0 if the Font parameter
  1227.        is NULL.
  1228.  
  1229. extras.lib/MultiAllocMemA                           extras.lib/MultiAllocMemA
  1230.  
  1231.    NAME
  1232.        MultiAllocMemA -- Multiple AllocMem.
  1233.        MultiAllocMem -- varargs stub.
  1234.  
  1235.    SYNOPSIS
  1236.        succes = MultiAllocMemA(Flags, MemTagList)
  1237.  
  1238.        BOOL MultiAllocMem(ULONG, struct MemTag *);
  1239.  
  1240.        succes = MultiAllocMemA(Flags, MemTag)
  1241.  
  1242.        BOOL MultiAllocMemA(Flags, ULONG, ...);
  1243.  
  1244.    FUNCTION
  1245.        Attempt to allocate one or more memory chunks
  1246.        using AllocMem.
  1247.  
  1248.    INPUTS
  1249.        Flags - MA_FAILSIZE0: fail all allocations if any
  1250.                have a size of 0.  if your application will be
  1251.                allocating memory of dynamic sizes, and if
  1252.                you want allocations of 0 bytes to fail, then
  1253.                set this flag.
  1254.        MemTag - pointer to an array of struct MemTag.
  1255.                   vt_Ptr is the address of a pointer.
  1256.                   vt_Size is the size of the allocation.
  1257.                   vt_MemFlags are the exec memory (MEMF_) flags. 
  1258.                 Last tag should have vt_Ptr = NULL.
  1259.                  
  1260.    RESULT
  1261.        zero if it couldn't allocate the requested memory. or non-zero
  1262.        on success. vt_Ptrs will be point to a allocated 
  1263.        memory chunk or NULL.  
  1264.  
  1265.    EXAMPLE
  1266.        EX1:
  1267.          struct foo *bar;
  1268.          STRPTR dest;
  1269.          APTR cow;
  1270.  
  1271.         if( MultiAllocMem(0,
  1272.                            &bar,  sizeof(struct foo),  MEMF_CLEAR,
  1273.                            &dest, 25,                  MEMF_PUBLIC,
  1274.                            &cow,  100,                 MEMF_FAST|MEMF_PUBLIC,
  1275.                            0))
  1276.          {
  1277.            ...
  1278.            MultiFreeMem(3,
  1279.                            bar  ,sizeof(struct foo),
  1280.                            dest ,25,
  1281.                            cow  ,100);
  1282.          }
  1283.  
  1284.        EX2: This will never fail.
  1285.          APTR foo;
  1286.          if(MultiAllocMem(0,
  1287.                            &foo,0,MEMF_CLEAR,
  1288.                            0)
  1289.          {...}
  1290.  
  1291.        EX3: This will always fail.
  1292.          APTR foo;
  1293.          if(MultiAllocMem(MA_FAILSIZE0,
  1294.                            &foo,0,MEMF_CLEAR,
  1295.                            0)
  1296.          {...}
  1297.  
  1298.    NOTES
  1299.        requires exec.library to be open.
  1300.  
  1301.        if the MA_FAILSIZE0 Flag is not set, 0 byte allocations
  1302.        will pass even though no memory will be allocated for that.
  1303.        entry and mt_Ptr will be set to 0.
  1304.  
  1305.        The memory allocated may be freed individually with 
  1306.        exec.library/FreeMem()
  1307.  
  1308.    BUGS
  1309.  
  1310.    SEE ALSO
  1311.        MultiAllocVecA(), MultiFreeVecA(), MultiFreeMemA(),
  1312.        MultiAllocPooledA(), MultiFreePooledA(),
  1313.        exec.library/AllocVec(), exec.library/FreeVec()
  1314.        exec.library/AllocMem(), exec.library/FreeMem()
  1315.        exec.library/AllocPooled(), exec.library/FreePooled()
  1316. extras.lib/MultiAllocPooledA                     extras.lib/MultiAllocPooledA
  1317.  
  1318.    NAME
  1319.        MultiAllocPooledA -- Multiple AllocPooled.
  1320.        MultiAllocPooled -- varargs stub.
  1321.  
  1322.    SYNOPSIS
  1323.        succes = MultiAllocPooledA(Flags, PoolTagList)
  1324.  
  1325.        BOOL MultiAllocPooled(ULONG, struct PoolTag*);
  1326.  
  1327.        succes = MultiAllocPooledA(Flags, PoolTag)
  1328.  
  1329.        BOOL MultiAllocPooledA(Flags, ULONG, ...);
  1330.  
  1331.    FUNCTION
  1332.        Attempt to allocate one or more memory chunks
  1333.        using AllocPooled.
  1334.  
  1335.    INPUTS
  1336.        Flags - MA_FAILSIZE0: fail all allocations if any
  1337.                have a size of 0.  if your application will be
  1338.                allocating memory of dynamic sizes, and if
  1339.                you want allocations of 0 bytes to fail, then
  1340.                set this flag.
  1341.        PoolTag - pointer to an array of struct PoolTag.
  1342.                   pt_Ptr is the address of a pointer.
  1343.                   pt_Size is the size of the allocation.
  1344.                 Last tag should have vt_Ptr = NULL.
  1345.                  
  1346.    RESULT
  1347.        zero if it couldn't allocate the requested memory. or non-zero
  1348.        on success. In either case, vt_Ptrs will be point to a allocated 
  1349.        memory chunk or NULL.  
  1350.  
  1351.    EXAMPLE
  1352.        EX1:
  1353.          APTR pool;
  1354.          struct foo *bar;
  1355.          STRPTR dest;
  1356.          APTR cow;
  1357.  
  1358.          if(pool=CreatePool(MEMF_ANY,300,300))
  1359.          {
  1360.            if( MultiAllocPooled(pool,0,
  1361.                            &bar,  sizeof(struct foo),
  1362.                            &dest, 50,       
  1363.                            &cow,  100,
  1364.                            0))
  1365.            {
  1366.              ...
  1367.              MultiFreePooled(pool,3,
  1368.                                bar,  sizeof(struct foo),
  1369.                                dest, 50,
  1370.                                cow,  100);
  1371.            }
  1372.            DeletePool(pool);
  1373.          }
  1374.  
  1375.        EX2: This will never fail.
  1376.          if(MultiAllocPooled(pool,0,
  1377.                            &foo, 0,
  1378.                            0)
  1379.          {...}
  1380.  
  1381.        EX3: This will always fail.
  1382.          if(MultiAllocPooled(pool,MA_FAILSIZE0,
  1383.                            &foo, 0,
  1384.                            0)
  1385.          {...}
  1386.  
  1387.    NOTES
  1388.        requires exec.library to be open.
  1389.  
  1390.        if the MA_FAILSIZE0 flag is not set, 0 byte allocations
  1391.        will pass even though no memory will be allocated for that.
  1392.        entry and mt_Ptr will be set to 0.
  1393.  
  1394.        The memory allocated may be freed individually with 
  1395.        exec.library/FreePooled()
  1396.  
  1397.    BUGS
  1398.  
  1399.    SEE ALSO
  1400.        MultiFreeVecA(), MultiAllocMemA(),MultiFreeMemA(),
  1401.        MultiFreePooledA(),
  1402.        exec.library/AllocVec(), exec.library/FreeVec()
  1403.        exec.library/AllocMem(), exec.library/FreeMem()
  1404.        exec.library/AllocPooled(), exec.library/FreePooled()
  1405. extras.lib/MultiAllocVecA                           extras.lib/MultiAllocVecA
  1406.  
  1407.    NAME
  1408.        MultiAllocVecA -- Multiple AllocVec.
  1409.        MultiAllocVec -- varargs stub.
  1410.  
  1411.    SYNOPSIS
  1412.        succes = MultiAllocVecA(Flags, VecTagList)
  1413.  
  1414.        BOOL MultiAllocVec(ULONG, struct VecTag *);
  1415.  
  1416.        succes = MultiAllocVecA(Flags, VecTag)
  1417.  
  1418.        BOOL MultiAllocVecA(Flags, ULONG, ...);
  1419.  
  1420.    FUNCTION
  1421.        Attempt to allocate one or more memory chunks
  1422.        using AllocVec.
  1423.  
  1424.    INPUTS
  1425.        Flags - MA_FAILSIZE0: fail all allocations if any
  1426.                have a size of 0.  if your application will be
  1427.                allocating memory of dynamic sizes, and if
  1428.                you want allocations of 0 bytes to fail, then
  1429.                set this flag.
  1430.        VecTag - pointer to an array of struct VecTag.
  1431.                   vt_Ptr is the address of a pointer.
  1432.                   vt_Size is the size of the allocation.
  1433.                   vt_MemFlags are the exec memory (MEMF_) flags. 
  1434.                 Last tag should have vt_Ptr = NULL.
  1435.                  
  1436.    RESULT
  1437.        zero if it couldn't allocate the requested memory. or non-zero
  1438.        on success. In either case, vt_Ptrs will be point to a allocated 
  1439.        memory chunk or NULL.  
  1440.  
  1441.    EXAMPLE
  1442.        EX1:
  1443.          struct foo *bar;
  1444.          STRPTR dest;
  1445.          APTR cow;
  1446.  
  1447.         if( MultiAllocVec(0,
  1448.                            &bar,  sizeof(struct foo),  MEMF_CLEAR,
  1449.                            &dest, strlen(str)+1,       MEMF_PUBLIC,
  1450.                            &cow,  100,                 MEMF_FAST|MEMF_PUBLIC,
  1451.                            0))
  1452.          {
  1453.            ...
  1454.            MultiFreeVec(3,bar,dest,cow);
  1455.          }
  1456.  
  1457.        EX2: This will never fail.
  1458.          APTR foo;
  1459.          if(MultiAllocVec(0,
  1460.                            &foo,0,MEMF_CLEAR,
  1461.                            0)
  1462.          {...}
  1463.  
  1464.        EX3: This will always fail.
  1465.          APTR foo;
  1466.          if(MultiAllocVec(MA_FAILSIZE0,
  1467.                            &foo,0,MEMF_CLEAR,
  1468.                            0)
  1469.          {...}
  1470.  
  1471.    NOTES
  1472.        requires exec.library to be open.
  1473.  
  1474.        if the MA_FAILSIZE0 flag is not set, 0 byte allocations
  1475.        will pass even though no memory will be allocated for that.
  1476.        entry and mt_Ptr will be set to 0.
  1477.  
  1478.        The memory allocated may be freed individually with 
  1479.        exec.library/FreeVec()
  1480.  
  1481.    BUGS
  1482.  
  1483.    SEE ALSO
  1484.        MultiFreeVecA(), MultiAllocMemA(),MultiFreeMemA(),
  1485.        MultiAllocPooledA(),MultiFreePooledA(),
  1486.        exec.library/AllocVec(), exec.library/FreeVec()
  1487.        exec.library/AllocMem(), exec.library/FreeMem()
  1488.        exec.library/AllocPooled(), exec.library/FreePooled()
  1489. extras.lib/MultiFreeMemA                             extras.lib/MultiFreeMemA
  1490.  
  1491.    NAME
  1492.        MultiFreeMemA -- Free multiple memory chunks.
  1493.        MultiFreeMem -- varargs stub.
  1494.  
  1495.    SYNOPSIS
  1496.        MultiFreeMemA(Args, FreeTagList)
  1497.  
  1498.        void MultiFreeMemA(ULONG, struct FreeTag *);
  1499.  
  1500.        MultiFreeMem(Args, FreeTag, ... )
  1501.  
  1502.        void MultiFreeMem(ULONG, ULONG, ... );
  1503.  
  1504.    FUNCTION
  1505.        Free multiple memory blocks allocated with MultiAllocMemA()
  1506.        or exec.library/AllocMem(). 
  1507.  
  1508.    INPUTS
  1509.        Args - Number of blocks that are to be freed.
  1510.        FreeTagList - An array of FreeTags. may be NULL.
  1511.                        ft_Ptr - contains a pointer to a
  1512.                                 memory block or NULL.
  1513.                        ft_Size - the size of the block.
  1514.  
  1515.    RESULT
  1516.        none.
  1517.  
  1518.    NOTES
  1519.        requires exec.library to be open.
  1520.  
  1521.    SEE ALSO
  1522.        MultiAllocVecA(), MultiFreeVecA(), MultiAllocMemA(),
  1523.        MultiAllocPooledA(), MultiFreePooledA(),
  1524.        exec.library/AllocVec(), exec.library/FreeVec()
  1525.        exec.library/AllocMem(), exec.library/FreeMem()
  1526.        exec.library/AllocPooled(), exec.library/FreePooled()
  1527.  
  1528. extras.lib/MultiFreePooledA                       extras.lib/MultiFreePooledA
  1529.  
  1530.    NAME
  1531.        MultiFreePooledA -- Free multiple memory chunks.
  1532.        MultiFreePooled -- varargs stub.
  1533.  
  1534.    SYNOPSIS
  1535.        MultiFreePooledA(Pool, Args, FreeTagList)
  1536.  
  1537.        void MultiFreePooledA(APTR, ULONG, struct FreeTag *);
  1538.  
  1539.        MultiFreePooled(Pool, Args, FreeTag, ... )
  1540.  
  1541.        void MultiFreePooled(APTR, ULONG, ULONG, ... );
  1542.  
  1543.    FUNCTION
  1544.        Free multiple memory blocks allocated with MultiAllocPooledA()
  1545.        or exec.library/AllocPooled(). 
  1546.  
  1547.    INPUTS
  1548.        Args - Number of blocks that are to be freed.
  1549.        FreeTagList - An array of FreeTags. may be NULL.
  1550.                        ft_Ptr - contains a pointer to a
  1551.                                 memory block or NULL.
  1552.                        ft_Size - the size of the block.
  1553.  
  1554.    RESULT
  1555.        none.
  1556.  
  1557.    NOTES
  1558.        requires exec.library to be open.
  1559.  
  1560.    SEE ALSO
  1561.        MultiAllocVecA(), MultiFreeVecA(), MultiAllocMemA(),
  1562.        MultiAllocPooledA(), MultiFreePooledA(),
  1563.        exec.library/AllocVec(), exec.library/FreeVec()
  1564.        exec.library/AllocMem(), exec.library/FreeMem()
  1565.        exec.library/AllocPooled(), exec.library/FreePooled()
  1566.  
  1567. extras.lib/MultiFreeVecA                             extras.lib/MultiFreeVecA
  1568.  
  1569.    NAME
  1570.        MultiFreeVecA -- Free multiple memory chunks.
  1571.        MultiFreeVec -- varargs stub.
  1572.  
  1573.    SYNOPSIS
  1574.        MultiFreeVecA(Args,MemBlockList)
  1575.  
  1576.        MultiFreeVecA(ULONG, APTR *);
  1577.  
  1578.        MultiFreeVec(Args, MemBlock)
  1579.  
  1580.        void MultiFreeVec(ULONG, ULONG, ... );
  1581.  
  1582.    FUNCTION
  1583.        Free multiple memory blocks allocated with MultiAllocVecA()
  1584.        or exec.library/AllocVec(). 
  1585.  
  1586.    INPUTS
  1587.        Args - Number of blocks that are to be freed.
  1588.        MemBlockList - An array of pointers to memory
  1589.                       blocks to be freed or NULL.
  1590.  
  1591.    RESULT
  1592.        none.
  1593.  
  1594.    NOTES
  1595.        requires exec.library to be open.
  1596.  
  1597.    SEE ALSO
  1598.        MultiAllocVecA(), MultiFreeVecA(), MultiAllocMemA(), MultiFreeMemA(),
  1599.        MultiAllocPooledA(), MultiFreePooledA(),
  1600.        exec.library/AllocVec(), exec.library/FreeVec()
  1601.        exec.library/AllocMem(), exec.library/FreeMem()
  1602.        exec.library/AllocPooled(), exec.library/FreePooled()
  1603. extras.lib/NextEntry                                     extras.lib/NextEntry
  1604.  
  1605.    NAME
  1606.        NextEntry - Find the next entry in a database file.
  1607.  
  1608.    SYNOPSIS
  1609.        error = NextEntry(File, EntryName, Buffer, BufferSize)
  1610.        
  1611.        LONG NextEntry(BPTR, STRPTR, STRPTR, ULONG);
  1612.  
  1613.    FUNCTION
  1614.        Seeks for the next entry in a database file.
  1615.  
  1616.    INPUTS
  1617.        File - AmigaDos file handle.
  1618.        EntryName - the name of the entry, usually "ENTRY".
  1619.               case is insignificant.
  1620.        Buffer - a buffer for reading data from a file.
  1621.        BufferSize - the size of the buffer.
  1622.  
  1623.    RESULT
  1624.        returns 0 on failure.  on success the file is positioned
  1625.        inside the entry.
  1626.  
  1627.    EXAMPLE
  1628.  
  1629.    NOTES
  1630.        This function is mainly used for other lib functions
  1631.  
  1632.    BUGS
  1633.  
  1634.    SEE ALSO
  1635.  
  1636. extras.lib/NextNNStr                                     extras.lib/NextNNStr
  1637.  
  1638.    NAME
  1639.        NextNNStr -- Get the next string in a double NULL terminted
  1640.                     string array (aka NNString).
  1641.  
  1642.    SYNOPSIS
  1643.        nextstring=NextNNStr(NNString)
  1644.  
  1645.        STRPTR NextNNStr(STRPTR);
  1646.  
  1647.    FUNCTION
  1648.        returns a pointer to the next string contained in a 
  1649.        double NULL teminated string array, or NULL.
  1650.  
  1651.    INPUTS
  1652.        NNString - A pointer to some part of a double NULL string.
  1653.  
  1654.    RESULT
  1655.        Pointer to the next string or NULL if there is no string.
  1656.  
  1657.    EXAMPLE
  1658.        ** this example steps through an NNString. **
  1659.  
  1660.        STRPTR NNString;
  1661.        STRPTR str;
  1662.  
  1663.        for(str=NNString; str; str=NextNNStr(str))
  1664.        {
  1665.          printf("%s\n",str);
  1666.        }
  1667.  
  1668.        The above can be simplified by using the ProcessNNStr macro
  1669.        defined in extras/nnstring.h
  1670.  
  1671.        STRPTR NNString;
  1672.        STRPTR str;
  1673.  
  1674.        ProcessNNStr(NNString,str)
  1675.        {
  1676.          printf("%s\n",str);
  1677.        }
  1678.  
  1679.    NOTES
  1680.  
  1681.    BUGS
  1682.  
  1683.    SEE ALSO
  1684.        NNString AddNNStr() ProcessNNStr, extras/macros.h
  1685.  
  1686. extras.lib/NNString_Overview                     extras.lib/NNString_Overview
  1687.  
  1688.    FUNCTION
  1689.        An NNString is an array of strings, stored end to end, ending
  1690.        with a double NULL.  Individual strings are seperated by NULLs.
  1691.  
  1692.    EXAMPLE
  1693.        An NNString representing this array of strings:
  1694.        "Cow" "Dog" "Barn"
  1695.        would look like this:
  1696.        "Cow\0Dog\0Barn\0\0"
  1697.  
  1698.    SEE ALSO
  1699.        NextNNStr(), ProcessNNStr, GetEntryData(), AddNNStr(), 
  1700.        NNStrLen()
  1701.  
  1702. extras.lib/NNStrLen                                       extras.lib/NNStrLen
  1703.  
  1704.    NAME
  1705.        NNStrLen -- Return the length of an NNString.
  1706.  
  1707.    SYNOPSIS
  1708.        length=NNStrLen(NNStr)
  1709.  
  1710.        LONG NNStrLen(STRPTR);
  1711.  
  1712.    FUNCTION
  1713.        Returns the length in bytes of an NNString, including the
  1714.        trailing NULLs. 
  1715.  
  1716.    INPUTS
  1717.        NNStr - NNString pointer.
  1718.  
  1719.    RESULT
  1720.        Size of NNStr include NULLs.
  1721.  
  1722.    SEE ALSO
  1723.  
  1724. extras.lib/NotBusy                                         extras.lib/NotBusy
  1725.  
  1726.    NAME
  1727.        NotBusy -- displays busy pointer.
  1728.  
  1729.    SYNOPSIS
  1730.        NotBusy(Window)
  1731.  
  1732.        void NotBusy(struct Window *);
  1733.  
  1734.    FUNCTION
  1735.        Removes the busy pointer for the specified
  1736.        window.
  1737.  
  1738.    INPUTS
  1739.        Window - the window to remove the busy pointer
  1740.                 from.
  1741.  
  1742.    RESULT
  1743.        None.
  1744.  
  1745.    NOTES
  1746.        requires intuition.library to be open.
  1747.  
  1748.        This does not change the Window's IDCMP flags.
  1749.        This function does nothing in WB versions less than
  1750.        3.0
  1751.  
  1752.    SEE ALSO
  1753.        Busy()
  1754.  
  1755. extras.lib/OBSOLETECheckInnerWindowSizextras.lib/OBSOLETECheckInnerWindowSize
  1756.  
  1757.    NAME
  1758.        CheckInnerWindowSize - See if a window will fit on a screen.
  1759.  
  1760.    SYNOPSIS
  1761.        windowfits = CheckInnerWindowSize(Scr, Width, Height,
  1762.                                      XScale, YScale)
  1763.  
  1764.        BOOL CheckInnerWindoeSize(struct Screen *, WORD, WORD, 
  1765.                                     float, float);
  1766.  
  1767.    FUNCTION
  1768.        This function checks to see if a window with the specified
  1769.        inner dimensions will fit on a screen.
  1770.  
  1771.    INPUTS
  1772.        Scr - the Screen the window is destine for.
  1773.        Width -  the base inner width of the window.
  1774.        Height - the base inner height of the window.
  1775.        XScale - the proposed x scale of the window.
  1776.        YScale - the proposed y scale of the window.
  1777.  
  1778.    RESULT
  1779.        Returns TRUE if the window will fit, and FALSE if not.
  1780.        if the XScale or YScale is <=0 it will also fail.
  1781.  
  1782.    SEE ALSO
  1783.        GetGUIScale(), CheckWindowSize()
  1784.  
  1785. extras.lib/OBSOLETECheckWindowSize         extras.lib/OBSOLETECheckWindowSize
  1786.  
  1787.    NAME
  1788.        CheckWindowSize - See if a window will fit on a screen.
  1789.  
  1790.    SYNOPSIS
  1791.        windowfits = CheckWindowSize(Scr, Width, Height,
  1792.                                      XScale, YScale)
  1793.  
  1794.        BOOL CheckWindowSize(struct Screen *, WORD, WORD, 
  1795.                                     float, float);
  1796.  
  1797.    FUNCTION
  1798.        This function checks to see if a window will fit on a screen.
  1799.  
  1800.    INPUTS
  1801.        Scr - the Screen the window is destine for.
  1802.        Width - the base width of the window.
  1803.        Height - the base height of the window.
  1804.        XScale - the proposed x scale of the window.
  1805.        YScale - the proposed y scale of the window.
  1806.  
  1807.    RESULT
  1808.        Returns TRUE if the window will fit, and FALSE if not.
  1809.        if the XScale or YScale is <=0 it will also fail.
  1810.  
  1811.    SEE ALSO
  1812.        GetGUIScale(), CheckInnerWindowSize()
  1813.  
  1814. extras.lib/OBSOLETEDrawBevelBoxes           extras.lib/OBSOLETEDrawBevelBoxes
  1815.  
  1816.    NAME
  1817.        DrawBevelBoxes -- draw a series of scaled bevel boxws.
  1818.  
  1819.    SYNOPSIS
  1820.        DrawBevelBoxes(Window, VisualInfo, BBoxes, NumBoxes,
  1821.              XScale, YScale);  
  1822.  
  1823.        void DrawBevelBoxes(struct Window *, APTR, 
  1824.              struct BevelBox *, LONG, float, float);
  1825.  
  1826.    FUNCTION
  1827.        Draws a series of scaled boxes.
  1828.  
  1829.    INPUTS
  1830.        Win - the Window to draw the bevel boxes in.
  1831.        VI - VisualInfo previously obtained by 
  1832.             gadtools.library/GetVisualInfoA()
  1833.        BBoxes - pointer to an array of struct BevelBox.
  1834.        NumBoxes - the number of entries in the array.
  1835.        XScale - 
  1836.        YScale - 
  1837.  
  1838.    EXAMPLE
  1839.  
  1840.    NOTES
  1841.  
  1842.    BUGS
  1843.  
  1844.    SEE ALSO
  1845.  
  1846. extras.lib/PD_PackData                                 extras.lib/PD_PackData
  1847.  
  1848.    NAME
  1849.        PD_PackData -- Pack supplied data into a memory block.
  1850.  
  1851.    SYNOPSIS
  1852.        packeddata = PD_PackData(Tags)
  1853.  
  1854.        struct PackedData *PD_PackData(Tag Tags, ... )
  1855.  
  1856.    FUNCTION
  1857.        Packs supplied data into a memory block, suitable for writing
  1858.        to disk.
  1859.  
  1860.    INPUTS
  1861.        Tags - a TagList.
  1862.            PD_Version - Adds a ULONG into the memory block.
  1863.                  Sets the version of the data.
  1864.  
  1865.            PD_BYTE - Adds a BYTE into the memory block.
  1866.            PD_UBYTE - Adds a UBYTE into the memory block.
  1867.  
  1868.            PD_WORD - Adds a WORD into the memory block. 
  1869.            PD_UWORD - Adds a UWORD into the memory block.
  1870.  
  1871.            PD_LONG - Adds a LONG into the memory block.
  1872.            PD_ULONG - Adds a ULONG into the memory block.
  1873.  
  1874.            PD_STRPTR - Adds a NULL terminated string into the memory block.
  1875.                  NULL pointers are supported
  1876.  
  1877.            PD_APTRSize - Adds the ULONG into the memory block,
  1878.                  Sets size for subsequent PD_APTRs.
  1879.            PD_APTR - Adds data into the memory block.  Size 
  1880.                  of data is set by previous PD_APTRSize.
  1881.                  if NULL, PD_APtrSize bytes are still written but are
  1882.                  unset.
  1883.  
  1884.            PD_BufferSize - Set the size of subsequent PD_Buffers
  1885.                  This tag does not add data to buffer.
  1886.  
  1887.            PD_Buffer     - Adds size of buffer, ULONG, followed by
  1888.                  data pointed to by ti_Data. 
  1889.                  See note for PD_UnpackData(()
  1890.            
  1891.            PD_MemoryFlags - Sets MemoryFlags for allocating 
  1892.  
  1893.  
  1894.    RESULT
  1895.  
  1896.    EXAMPLE
  1897.  
  1898.    NOTES
  1899.      Except for BYTEs, data is UWORD aligned, pads are inserted as needed.
  1900.  
  1901.      PackedData->pd_Data
  1902.      {
  1903.        ULONG privatelength
  1904.        {private bytes}
  1905.        user data
  1906.      }     
  1907.  
  1908.  
  1909.    BUGS
  1910.  
  1911.    SEE ALSO
  1912.  
  1913. extras.lib/PD_UnpackData                             extras.lib/PD_UnpackData
  1914.  
  1915.    NAME
  1916.        PD_UnpackData -- Unpack memory block.
  1917.  
  1918.    SYNOPSIS
  1919.        success = PD_UnpackData(Tags)
  1920.  
  1921.        BOOL *PD_UnpackData(Tag Tags, ... )
  1922.  
  1923.    FUNCTION
  1924.        Packs supplied data into a memory block, suitable for writing
  1925.        to disk.
  1926.  
  1927.    INPUTS
  1928.        Tags - a TagList.
  1929.            For most tags, ti_Data is a storage pointer, if NULL the 
  1930.            data is parsed but not stored.
  1931.  
  1932.            PD_Version   - (ULONG *) Reads the version of the data.
  1933.  
  1934.            PD_IfVersion - (ULONG) Once PD_Version has been read, you can
  1935.                this tag to stop data processing if PD_Version is lower than
  1936.                the value of this tag. 
  1937.  
  1938.            PD_BYTE - (BYTE *) Read a BYTE
  1939.            PD_UBYTE -(UBYTE *)
  1940.  
  1941.            PD_WORD - (WORD *) Read a WORD
  1942.            PD_UWORD -(UWORD *)
  1943.  
  1944.            PD_LONG - (LONG *) Read a LONG
  1945.            PD_ULONG -(LONG *)
  1946.  
  1947.            PD_STRPTR - (STRPTR *) AllocVec()s Memory for new STRPTR
  1948.                if PD_FreeSTRPTR is set, existing STRPTR is FreeVec()ed.
  1949.  
  1950.            PD_APTRSize - (ULONG *) Reads the amount of bytes that subsequent
  1951.                PD_APTRs read from the packed data.
  1952.  
  1953.            PD_APTR - Reads data from the memory block.  Size 
  1954.                  of data is set by previous PD_APTRSize.
  1955.                  if NULL, PD_APtrSize bytes are still written but are
  1956.                  unset.
  1957.  
  1958.            PD_BufferSize - (ULONG) Set data size for subsequent PD_Struct 
  1959.                  reads. This tag does not read any data, you must specify 
  1960.                  the size of your Buffer.
  1961.  
  1962.            PD_Buffer - (APTR) Data is copied to existing memory, the amount 
  1963.                  of data copied will be the lesser of PD_BufferSize or the
  1964.                  size stored in the packed data block.
  1965.            
  1966.            PD_MemoryFlags - Sets MemoryFlags for allocating 
  1967.  
  1968.  
  1969.    RESULT
  1970.  
  1971.    EXAMPLE
  1972.        PD_UnpackData(pd,
  1973.            PD_Version,     &dataversion, // store version number
  1974.            PD_BYTE,        &byte1,
  1975.            PD_BYTE,        0,            // byte not stored.
  1976.            PD_STRPTR,      &string,
  1977.  
  1978.            PD_IfVersion,   1, /* the following will only be read id PD_Versio
  1979. n >= 1 */
  1980.            PD_APTRSize,    10,
  1981.            PD_APTR,        &memchunk1,
  1982.            PD_APTR,        &memchunk2,
  1983.       
  1984.            PD_IfVersion,   2, /* the following will only be read id PD_Versio
  1985. n >= 2 */
  1986.            PD_STRUCT(mystruct),
  1987.       
  1988.            TAG_DONE,       0))
  1989.  
  1990.    BUGS
  1991.  
  1992.    SEE ALSO
  1993.  
  1994. extras.lib/PhraseInStr                                 extras.lib/PhraseInStr
  1995.  
  1996.    NAME
  1997.        PhraseInStr -- Find a phrase or word in a string.
  1998.  
  1999.    SYNOPSIS
  2000.        str = PhraseInStr(InStr, Phrase)
  2001.  
  2002.        STRPTR PhraseInStr(STRPTR , Phrase)
  2003.  
  2004.    FUNCTION
  2005.        Locates a phrase or word in a string.
  2006.  
  2007.    INPUTS
  2008.        InStr - String to search in.
  2009.        Phrase to search for.
  2010.  
  2011.    RESULT
  2012.        returns pointer to phrase in InStr or NULL.
  2013.  
  2014.    EXAMPLE
  2015.  
  2016.    NOTES
  2017.        case insensitive.
  2018.  
  2019.    BUGS
  2020.  
  2021.    SEE ALSO
  2022.  
  2023. extras.lib/RenderText                                   extras.lib/RenderText
  2024.  
  2025.    NAME
  2026.        RenderTextA -- Write text into a RastPort.
  2027.        RenderText -- varargs stub.
  2028.  
  2029.    SYNOPSIS
  2030.        reserved = RenderTextA( RP, String, TagList)
  2031.  
  2032.        LONG RenderTextA( struct RastPort *, STRPTR, 
  2033.                          struct TagItem *);
  2034.  
  2035.        reserved = RenderText( RP, String, Tags, ... )
  2036.  
  2037.        LONG RenderText( struct RastPort *, STRPTR, 
  2038.                         Tag, ...);
  2039.  
  2040.    FUNCTION
  2041.        Writes text into a Rastport, basically an interface
  2042.        to the graphics.library/Text() function.
  2043.  
  2044.    INPUTS
  2045.        RP - rastport to write to.
  2046.        String - the string to write.
  2047.        TagList - an array of TagItems.
  2048.          RT_Baseline - baseline of the cursor. 
  2049.                        default RastPort->cp_y
  2050.          RT_XPos     - horizontal position of the cursor.
  2051.                        default RastPort->cp_x
  2052.          RT_MaxWidth - maximum pixel length of text, excess
  2053.                        characters will be clipped.
  2054.          RT_Justification - RTJ_???  (default _LEFT)
  2055.          RT_TextFont - struct TextFont * from OpenFont()
  2056.          RT_Strlen   - number of characters in string.
  2057.          RT_TextLength - (ULONG *) Width in pixels of printed texted.
  2058.  
  2059.  
  2060.    RESULT
  2061.        Number of characters drawn.
  2062.  
  2063.    BUGS
  2064.        RenderText does not reset a RastPort's TextFont
  2065.        after using RT_TextFont. 
  2066.  
  2067.    SEE ALSO
  2068.        mlr_rendertext.image image class.
  2069.  
  2070. extras.lib/StrFontLen                                   extras.lib/StrFontLen
  2071.  
  2072.    NAME
  2073.        StrFontLen - get the pixel length of a string.
  2074.  
  2075.    SYNOPSIS
  2076.        length=StrFontLen(Font, Str)
  2077.  
  2078.        LONG StrFontLen(struct TextFont *,STRPTR);
  2079.  
  2080.    FUNCTION
  2081.        This function returns the number of pixels a string
  2082.        would occupy if rendered in the specified Font.
  2083.  
  2084.    INPUTS
  2085.        Font - struct TextFont * previously opened by 
  2086.               OpenFont() or OpenDiskFont().
  2087.        Str - a pointer to a null terminated string.
  2088.  
  2089.    RESULT
  2090.        the pixel length of the string or 0 if either parameter
  2091.        is NULL.
  2092.  
  2093. extras.lib/Strip                                             extras.lib/Strip
  2094.  
  2095.    NAME
  2096.        Strip - Remove leading and trailing white spaces.
  2097.  
  2098.    SYNOPSIS
  2099.        Strip(Str)       
  2100.  
  2101.        void Strip(STRPTR);
  2102.  
  2103.    FUNCTION
  2104.        This function removes leading and trailing whites-paces
  2105.        from a string.  White-spaces are determined by the 
  2106.        IsWhiteSpace() function.
  2107.  
  2108.    INPUTS
  2109.        Str - a null terminated string pointer.
  2110.  
  2111.    RESULT
  2112.        none.
  2113.  
  2114.    EXAMPLE
  2115.  
  2116.    NOTES
  2117.        Modifies existing string memory.
  2118.  
  2119.    BUGS
  2120.        Will not work on NNStr used by other some functions in 
  2121.        the extras.lib.
  2122.  
  2123.    SEE ALSO
  2124.        IsWhiteSpace().
  2125.  
  2126. extras.lib/StrIStr                                         extras.lib/StrIStr
  2127.  
  2128.    NAME
  2129.        StrIStr -- search for a string in another string, case 
  2130.                   insenseitive.
  2131.  
  2132.    SYNOPSIS
  2133.        StrIStr(InStr,SearchStr)
  2134.  
  2135.        STRPTR StrIStr(STRPTR InStr,STRPTR SearchStr);
  2136.  
  2137.    FUNCTION
  2138.        Seach for a string inside another, case insensitive.
  2139.  
  2140.    INPUTS
  2141.        InStr - the string to search in.
  2142.        SearchStr - the string to search for.
  2143.  
  2144.    RESULT
  2145.        returns a pointer in InStr that matches SearchStr, or NULL
  2146.        if no match was found.
  2147.  
  2148. extras.lib/StrLength                                     extras.lib/StrLength
  2149.  
  2150.    NAME
  2151.        StrLength -- Get the pixel length of a string.
  2152.  
  2153.    SYNOPSIS
  2154.        Len = StrLength(Tags)
  2155.        
  2156.        LONG StrLength(Tag, ... );
  2157.  
  2158.    FUNCTION
  2159.        Find the length of a given string.  If multiple strings
  2160.        are given, returns the longest length.
  2161.  
  2162.    INPUTS
  2163.        Tags 
  2164.          SL_TextFont - (struct TextFont *)The font the string will
  2165.            be rendered in. (required)
  2166.          SL_IgnoreChars - (STRPTR) Null terminated string of characters
  2167.            to ignore from the length calculation, useful for underscores
  2168.            in gadget text, etc.
  2169.          SL_String - (STRPTR) String to size.
  2170.  
  2171.    RESULT
  2172.        Length in pixels of longest string.
  2173.  
  2174.    EXAMPLE
  2175.          *find length of button text without the "_" 
  2176.          len= StrLength(SL_TextFont     ,TF,
  2177.                         SL_String       ,"_Button",
  2178.                         SL_IgnoreChars  ,"_",
  2179.                         TAG_DONE);
  2180.  
  2181.          * find maximum length of red, green and blue without "_"
  2182.          len= StrLength(SL_TextFont     ,TF,
  2183.                         SL_String       ,"_Red",
  2184.                         SL_String       ,"_Green",
  2185.                         SL_String       ,"_Blue",
  2186.                         SL_IgnoreChars  ,"_",
  2187.                         TAG_DONE);
  2188.  
  2189.    NOTES
  2190.  
  2191.    BUGS
  2192.  
  2193.    SEE ALSO
  2194.  
  2195. extras.lib/thread_EndThread                       extras.lib/thread_EndThread
  2196.  
  2197.    NAME
  2198.        thread_EndThread -- end a thread.
  2199.  
  2200.    SYNOPSIS
  2201.  
  2202.  
  2203.  
  2204.  
  2205.  
  2206.  
  2207.    FUNCTION
  2208.  
  2209.  
  2210.    INPUTS
  2211.  
  2212.    RESULT
  2213.  
  2214.    EXAMPLE
  2215.  
  2216.    NOTES
  2217.        Note, this function waits for a reply.
  2218.  
  2219.    BUGS
  2220.  
  2221.    SEE ALSO
  2222.  
  2223. extras.lib/thread_PutTMsg                           extras.lib/thread_PutTMsg
  2224.  
  2225.    NAME
  2226.        thread_PutTMsg -- Send a ThreadMessage to a thread.
  2227.  
  2228.    SYNOPSIS
  2229.  
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.    FUNCTION
  2236.  
  2237.  
  2238.    INPUTS
  2239.  
  2240.    RESULT
  2241.  
  2242.    EXAMPLE
  2243.  
  2244.    NOTES
  2245.        Note, this function does not wait for a reply.
  2246.  
  2247.    BUGS
  2248.  
  2249.    SEE ALSO
  2250.  
  2251. extras.lib/thread_PutTMsg_TagList           extras.lib/thread_PutTMsg_TagList
  2252.  
  2253.    NAME
  2254.        thread_PutTMsg_TagList -- Send a TagListTMsg to a thread.
  2255.  
  2256.    SYNOPSIS
  2257.  
  2258.  
  2259.  
  2260.  
  2261.  
  2262.  
  2263.    FUNCTION
  2264.  
  2265.  
  2266.    INPUTS
  2267.  
  2268.    RESULT
  2269.  
  2270.    EXAMPLE
  2271.  
  2272.    NOTES
  2273.        Note, this function waits for a reply.
  2274.  
  2275.    BUGS
  2276.  
  2277.    SEE ALSO
  2278.  
  2279. extras.lib/thread_StartThread                   extras.lib/thread_StartThread
  2280.  
  2281.    NAME
  2282.        thread_StartThread -- Create a thread.
  2283.  
  2284.    SYNOPSIS
  2285.        Thread thread_StartThread(Tags)
  2286.  
  2287.        struct Thread *thread_StartThread(Tag, ... );
  2288.  
  2289.    FUNCTION
  2290.        Creates and starts a new thread (Process).
  2291.  
  2292.    INPUTS
  2293.        Tags - TagList (on stack)
  2294.          TA_Name - Name of thread, defaults to "Thread".
  2295.          TA_Stack - Stacksize, default 8192.
  2296.          TA_Priority - default -1
  2297.          TA_MsgHandler - Function to handle thread messages.
  2298.          TA_UserData - (APTR)
  2299.  
  2300.    RESULT
  2301.        Pointer to the newly created Thread, or NULL on failure.
  2302.        The Thread stucture is ReadOnly, except for
  2303.          t_Node, UserData and ThreadData
  2304.  
  2305.    NOTES
  2306.        It's suggested that ThreadData be used store local data
  2307.        for the Thread.
  2308.  
  2309.    BUGS
  2310.  
  2311.    SEE ALSO
  2312.  
  2313. extras.lib/UpdateProgressMeterA               extras.lib/UpdateProgressMeterA
  2314.  
  2315.    NAME
  2316.        UpdateProgressMeterA -- Change ProgressMeter attributes.
  2317.        UpdateProgressMeter -- varargs stub.
  2318.  
  2319.    SYNOPSIS
  2320.        numProcessed UpdateProgressMeterA(PM,TagList)
  2321.  
  2322.        LONG UpdateProgressMeterA(ProgressMeter ,struct TagItem *);
  2323.  
  2324.        numProcessed UpdateProgressMeter(PM,FirstTag)
  2325.  
  2326.        LONG UpdateProgressMeter(ProgressMeter , Tag, ...);
  2327.  
  2328.    FUNCTION
  2329.        Updates a ProgressMeter's attributes  and refreshes
  2330.        it as neccessary.
  2331.  
  2332.    INPUTS
  2333.        PM - Pointer to an existing ProgressMeter or NULL.
  2334.        TagList - TagList of attributes to change or NULL.
  2335.            Only these four tags are processed.
  2336.              PM_QueryCancel
  2337.              PM_MeterValue
  2338.              PM_LowValue
  2339.              PM_HighValue
  2340.  
  2341.    RESULT
  2342.        returns the number of tags processed.
  2343.  
  2344.    EXAMPLE
  2345.  
  2346.    NOTES
  2347.      requires diskfont, exec, gadtools, graphics, intuition & utility
  2348.      libraries to be open.
  2349.  
  2350.    BUGS
  2351.  
  2352.    SEE ALSO
  2353.      AllocProgressMeterA(), FreeProgressMeter() 
  2354.  
  2355.